home *** CD-ROM | disk | FTP | other *** search
/ Mac Magazin/MacEasy 21 / Mac Magazin and MacEasy Magazine CD - Issue 21.iso / Wissenschaft & Technik / yorick12vr1-nofpu folder / startup / graph.i < prev    next >
Text File  |  1995-12-12  |  51KB  |  1,139 lines
  1. /*
  2.     GRAPH.I
  3.     Declarations of Yorick graphics functions.
  4.  
  5.     $Id: graph.i,v 1.1 1993/08/27 18:32:09 munro Exp $
  6.  */
  7. /*    Copyright (c) 1994.  The Regents of the University of California.
  8.                     All rights reserved.  */
  9.  
  10. /*--------------------------------------------------------------------------*/
  11. /* Control functions */
  12.  
  13. extern window;
  14. /* DOCUMENT window, n, display="host:server.screen", dpi=100/75, wait=0/1,
  15.                        private=0/1, hcp="hcp_filename", dump=0/1,
  16.                        legends=1/0, style="style_sheet_filename"
  17.      select window N as the current graphics output window.  N may
  18.      range from 0 to 7, inclusive.  Each graphics window corresponds to
  19.      an X window, and optionally has its own associated hardcopy file.
  20.      If N is omitted, it defaults to the current coordinate system.
  21.  
  22.      The X window will appear on your default display at 75 dpi, unless
  23.      you specify the display and/or dpi keywords.  A dpi=100 X window
  24.      is larger than a dpi=75 X window; both represent the same thing
  25.      on paper.  Use display="" to create a graphics window which has
  26.      no associated X window (you should do this if you want to make
  27.      plots in a non-interactive batch mode).
  28.  
  29.      By default, an X window will attempt to use shared colors, which
  30.      permits several Yorick graphics windows (including windows from
  31.      multiple instances of Yorick) to use a common palette.  You can
  32.      force an X window to post its own colormap (set its colormap
  33.      attribute) with the private=1 keyword.  You will most likely have
  34.      to fiddle with your window manager to understand how it handles
  35.      colormap focus if you do this.  Use private=0 to return to shared
  36.      colors.
  37.  
  38.      By default, Yorick will not wait for the X window to become visible;
  39.      code which creates a new window, then plots a series of frames to
  40.      that window should use wait=1 to assure that all frames are actually
  41.      plotted.
  42.  
  43.      By default, a graphics window does NOT have a hardcopy file
  44.      of its own -- any request for hardcopy are directed to the
  45.      default hardcopy file, so hardcopy output from any window goes
  46.      to a single file.  By specifying the hcp keyword, however, a
  47.      hardcopy file unique to this window will be created.  If the
  48.      "hcp_filename" ends in ".ps", the hardcopy file will be a PostScript
  49.      file; otherwise, hardcopy files are in binary CGM format.  Use
  50.      hcp="" to revert to the default hardcopy file (closing the window
  51.      specific file, if any).  The legends keyword, if present, controls
  52.      whether the curve legends are (legends=1, the default) or are not
  53.      (legends=0) dumped to the hardcopy file.  The dump keyword, if
  54.      present, controls whether all colors are converted to a gray scale
  55.      (dump=0, the default), or the current palette is dumped at the
  56.      beginning of each page of hardcopy output.  (The legends keyword
  57.      applies to all pictures dumped to hardcopy from this graphics
  58.      window.  The dump keyword applies only to the specific hardcopy
  59.      file defined using the hcp keyword -- use the dump keyword in the
  60.      hcp_file command to get the same effect in the default hardcopy
  61.      file.)
  62.  
  63.      If both display="" and hcp="", the graphics window will be
  64.      entirely eliminated.
  65.  
  66.      The style keyword, if present, specifies the name of a Gist style
  67.      sheet file; the default is "work.gs".  The style sheet determines
  68.      the number and location of coordinate systems, tick and label styles,
  69.      and the like.  Other choices include "axes.gs", "boxed.gs",
  70.      "work2.gs", and "boxed2.gs".
  71.  
  72.      If invoked as a function, window(...) returns the current
  73.      window number.
  74.    SEE ALSO: plsys, hcp_file, fma, hcp, redraw, palette, animate, plg,
  75.              winkill, gridxy
  76.  */
  77.  
  78. func winkill(n)
  79. /* DOCUMENT winkill
  80.          or winkill, n
  81.      deletes the current graphics window, or graphics window N (0-7).
  82.    SEE ALSO: window
  83.  */
  84. {
  85.   window, n, display="", hcp="";
  86. }
  87.  
  88. extern current_window;
  89. /* DOCUMENT n= current_window()
  90.      returns the number of the current graphics window, or -1 if none.
  91.  */
  92.  
  93. extern hcp_file;
  94. /* DOCUMENT hcp_file, filename, dump=0/1
  95.      sets the default hardcopy file to FILENAME.  If FILENAME ends with
  96.      ".ps", the file will be a PostScript file, otherwise it will be a
  97.      binary CGM file.  By default, the hardcopy file name will be
  98.      "Aa00.cgm", or "Ab00.cgm" if that exists, or "Ac00.cgm" if both
  99.      exist, and so on.  The default hardcopy file gets hardcopy from all
  100.      graphics windows which do not have their own specific hardcopy file
  101.      (see the window command).  If the dump keyword is present and non-zero,
  102.      the current palette will be dumped at the beginning of each frame
  103.      of the default hardcopy file.  With dump=0, the default behavior of
  104.      converting all colors to a gray scale is restored.
  105.    SEE ALSO: window, fma, hcp, plg
  106.  */
  107.  
  108. extern hcp_finish;
  109. /* DOCUMENT filename= hcp_finish()
  110.          or filename= hcp_finish(n)
  111.      closes the current hardcopy file and returns the filename.
  112.      If N is specified, closes the hcp file associated with window N
  113.      and returns its name; use hcp_finish(-1) to close the default
  114.      hardcopy file.
  115.    SEE ALSO: window, fma, hcp, hcp_out, plg
  116.  */
  117.  
  118. func hcp_out(n,keep=)
  119. /* DOCUMENT hcp_out
  120.          or hcp_out, n
  121.      finishes the current hardcopy file and sends it to the printer.
  122.      If N is specified, prints the hcp file associated with window N;
  123.      use hcp_out,-1 to print the default hardcopy file.
  124.      Unless the KEEP keyword is supplied and non-zero, the file will
  125.      be deleted after it is processed by gist and sent to lpr.
  126.    SEE ALSO: window, fma, hcp, hcp_finish, plg
  127.  */
  128. {
  129.   filename= hcp_finish();
  130.   if (filename) {
  131.     if (strpart(filename,-2:0)==".ps")
  132.       system, swrite(format=LPR_FORMAT, filename);
  133.     else
  134.       system, swrite(format=GIST_FORMAT, filename);
  135.     if (!keep) remove, filename;
  136.   }
  137. }
  138.  
  139. func eps(name)
  140. /* DOCUMENT eps, name
  141.      writes the picture in the current graphics window to the Encapsulated
  142.      PostScript file NAME+".epsi" (i.e.- the suffix .epsi is added to NAME).
  143.      The eps function requires the ps2epsi utility which comes with the
  144.      project GNU Ghostscript program.  Any hardcopy file associated with
  145.      the current window is first closed, but the default hardcopy file is
  146.      unaffected.  As a side effect, legends are turned off and color table
  147.      dumping is turned on for the current window.
  148.      The external variable PS2EPSI_FORMAT contains the format for the
  149.      command to start the ps2epsi program.
  150.    SEE ALSO: window, fma, hcp, hcp_finish, plg
  151.  */
  152. {
  153.   name+= ".ps";
  154.   window, hcp=name, dump=1, legends=0;
  155.   hcp;
  156.   window, hcp="";
  157.   system, swrite(format=PS2EPSI_FORMAT, name);
  158.   remove, name;
  159. }
  160. if (is_void(PS2EPSI_FORMAT)) PS2EPSI_FORMAT= "ps2epsi %s";
  161.  
  162. extern fma;
  163. /* DOCUMENT fma
  164.      frame advance the current graphics window.  The current picture
  165.      remains displayed in the associated X window until the next element
  166.      is actually plotted.
  167.    SEE ALSO: window, hcp, animate, plg
  168.  */
  169.  
  170. extern hcp;
  171. extern hcpon;
  172. extern hcpoff;
  173. /* DOCUMENT hcp
  174.             hcpon
  175.         hcpoff
  176.      The hcp command sends the picture displayed in the current graphics
  177.      window to the hardcopy file.  (The name of the default hardcopy file
  178.      can be specified using hcp_file; each individual graphics window may
  179.      have its own hardcopy file as specified by the window command.)
  180.      The hcpon command causes every fma (frame advance) command to do
  181.      and implicit hcp, so that every frame is sent to the hardcopy file.
  182.      The hcpoff command reverts to the default "demand only" mode.
  183.    SEE ALSO: window, fma, plg
  184.  */
  185.  
  186. extern redraw;
  187. /* DOCUMENT redraw
  188.      redraws the X window associated with the current graphics window.
  189.    SEE ALSO: window, fma, hcp, plg
  190.  */
  191.  
  192. extern palette;
  193. /* DOCUMENT palette, filename
  194.          or palette, source_window_number
  195.          or palette, red, green, blue, ntsc=1/0
  196.          or palette, red, green, blue, gray
  197.      or palette, red, green, blue, query=1
  198.      or palette, red, green, blue, gray, query=1
  199.      sets (or retrieves with query=1) the palette for the current
  200.      graphics window.  The FILENAME is the name of a Gist palette file;
  201.      the standard palettes are "earth.gp", "stern.gp", "rainbow.gp",
  202.      "heat.gp", "gray.gp", and "yarg.gp".  Use the maxcolors keyword
  203.      in the pldefault command to put an upper limit on the number of
  204.      colors which will be read from the palette in FILENAME.
  205.  
  206.      In the second form, the palette for the current window is copied
  207.      from the SOURCE_WINDOW_NUMBER.  If the X colormap for the window is
  208.      private, there will still be two separate X colormaps for the two
  209.      windows, but they will have the same color values.
  210.  
  211.      In the third form, RED, GREEN, and BLUE are 1-D arrays of the same
  212.      length specifying the palette you wish to install; the values
  213.      should vary between 0 and 255, and your palette should have no
  214.      more than 240 colors.  If ntsc=0, monochrome devices (such as most
  215.      laser printers) will use the average brightness to translate your
  216.      colors into gray; otherwise, the NTSC (television) averaging will
  217.      be used (.30*RED+.59*GREEN+.11*BLUE).  Alternatively, you can specify
  218.      GRAY explicitly.
  219.  
  220.      Ordinarily, the palette is not dumped to a hardcopy file
  221.      (color hardcopy is still rare and expensive), but you can
  222.      force the palette to dump using the window or hcp_file commands.
  223.  
  224.      See the dump= keyword for the hcp_file and window commands if you
  225.      are having trouble getting color in your hardcopy files.
  226.  
  227.    SEE ALSO: window, fma, hcp, pldefault, plg
  228.  */
  229.  
  230. extern animate;
  231. /* DOCUMENT animate
  232.          or animate, 0/1
  233.      without any arguments, toggles animation mode; with argument 0,
  234.      turns off animation mode, with argument 1 turns on animation mode.
  235.      In animation mode, the X window associated with a graphics window
  236.      is actually an offscreen pixmap which is bit-blitted onscreen
  237.      when an fma command is issued.  This is confusing unless you are
  238.      actually trying to make a movie, but results in smoother animation
  239.      if you are.  Generally, you should turn animation on, run your movie,
  240.      then turn it off.
  241.    SEE ALSO: window, fma, plg
  242.  */
  243.  
  244. extern plsys;
  245. /* DOCUMENT plsys, n
  246.      sets the current coordinate system to number N in the current
  247.      graphics window.  If N equals 0, subsequent elements will be
  248.      plotted in absolute NDC coordinates outside of any coordinate
  249.      system.  The default style sheet "work.gs" defines only a single
  250.      coordinate system, so the only other choice is N equal 1.  You
  251.      can make up your own style sheet (using a text editor) which
  252.      defines mulitple coordinate systems.  You need to do this if
  253.      you want to display four plots side by side on a single page,
  254.      for example.  The standard style sheets "work2.gs" and "boxed2.gs"
  255.      define two overlayed coordinate systems with the first labeled
  256.      to the right of the plot and the second labeled to the left of
  257.      the plot.  When using overlayed coordinate systems, it is your
  258.      responsibility to ensure that the x-axis limits in the two
  259.      systems are identical.
  260.    SEE ALSO: window, limits, plg
  261.  */
  262.  
  263. /*--------------------------------------------------------------------------*/
  264. /* Plotting functions (output primitives) */
  265.  
  266. extern plg;
  267. /* DOCUMENT plg, y, x
  268.          or plg, y
  269.      plots a graph of Y versus X.  Y and X must be 1-D arrays of equal
  270.      length; if X is omitted, it defaults to [1, 2, ..., numberof(Y)].
  271.      The following keywords are legal (each has a separate help entry):
  272.    KEYWORDS: legend, hide
  273.          type, width, color, closed, smooth
  274.              marks, marker, mspace, mphase
  275.          rays, arrowl, arroww, rspace, rphase
  276.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp
  277.              limits, logxy, range, fma, hcp
  278.  */
  279.  
  280. extern plm;
  281. /* DOCUMENT plm, y, x, boundary=0/1, inhibit=0/1/2
  282.          or plm, y, x, ireg, boundary=0/1, inhibit=0/1/2
  283.      or plm, boundary=0/1, inhibit=0/1/2
  284.      plots a mesh of Y versus X.  Y and X must be 2-D arrays with equal
  285.      dimensions.  If present, IREG must be a 2-D region number array
  286.      for the mesh, with the same dimensions as X and Y.  The values of
  287.      IREG should be positive region numbers, and zero for zones which do
  288.      not exist.  The first row and column of IREG never correspond to any
  289.      zone, and should always be zero.  The default IREG is 1 everywhere
  290.      else.  If present, the BOUNDARY keyword determines whether the
  291.      entire mesh is to be plotted (boundary=0, the default), or just the
  292.      boundary of the selected region (boundary=1).  If present, the
  293.      INHIBIT keyword causes the (X(,j),Y(,j)) lines to not be plotted
  294.      (inhibit=1), or the (X(i,),Y(i,)) lines to not be plotted (inhibit=2).
  295.      By default (inhibit=0), mesh lines in both logical directions are
  296.      plotted.
  297.      The Y, X, and IREG arguments may all be omitted to default to the
  298.      mesh set by the most recent plmesh call.
  299.      The following keywords are legal (each has a separate help entry):
  300.    KEYWORDS: legend, hide
  301.          type, width, color
  302.          region
  303.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh
  304.              limits, logxy, range, fma, hcp
  305.  */
  306.  
  307. extern plmesh;
  308. /* DOCUMENT plmesh, y, x, ireg, triangle=tri_array
  309.          or plmesh
  310.      sets the default mesh for subsequent plm, plc, plv, and plf calls.
  311.      In the second form, deletes the default mesh (until you do this,
  312.      or switch to a new default mesh, the default mesh arrays persist and
  313.      take up space in memory).  The Y, X, and IREG arrays should all be
  314.      the same shape; Y and X will be converted to double, and IREG will
  315.      be converted to int.  If IREG is omitted, it defaults to IREG(1,)=
  316.      IREG(,1)= 0, IREG(2:,2:)=1; that is, region number 1 is the whole
  317.      mesh.  The triangulation array TRI_ARRAY is used by plc; the
  318.      correspondence between TRI_ARRAY indices and zone indices is the
  319.      same as for IREG, and its default value is all zero.
  320.      The IREG or TRI_ARRAY arguments may be supplied without Y and X
  321.      to change the region numbering or triangulation for a given set of
  322.      mesh coordinates.  However, a default Y and X must already have been
  323.      defined if you do this.
  324.      If Y is supplied, X must be supplied, and vice-versa.
  325.    SEE ALSO: plm, plc, plv, plf, plfp
  326.  */
  327.  
  328. extern plc;
  329. /* DOCUMENT plc, z, y, x, levs=z_values
  330.          or plc, z, y, x, ireg, levs=z_values
  331.      or plc, z, levs=z_values
  332.      plots a contours of Z on the mesh Y versus X.  Y, X, and IREG are
  333.      as for plm.  The Z array must have the same shape as Y and X.
  334.      The function being contoured takes the value Z at each point
  335.      (X,Y) -- that is, the Z array is presumed to be point-centered.
  336.      The Y, X, and IREG arguments may all be omitted to default to the
  337.      mesh set by the most recent plmesh call.
  338.      The LEVS keyword is a list of the values of Z at which you want
  339.      contour curves.  The default is eight contours spanning the
  340.      range of Z.
  341.      The following keywords are legal (each has a separate help entry):
  342.    KEYWORDS: legend, hide
  343.          type, width, color, smooth
  344.              marks, marker, mspace, mphase
  345.          smooth, triangle, region
  346.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh
  347.              limits, logxy, range, fma, hcp
  348.  */
  349.  
  350. extern plv;
  351. /* DOCUMENT plv, vy, vx, y, x, scale=dt
  352.          or plv, vy, vx, y, x, ireg, scale=dt
  353.      or plv, vy, vx, scale=dt
  354.      plots a vector field (VX,VY) on the mesh (X,Y).  Y, X, and IREG are
  355.      as for plm.  The VY and VX arrays must have the same shape as Y and X.
  356.      The Y, X, and IREG arguments may all be omitted to default to the
  357.      mesh set by the most recent plmesh call.
  358.      The SCALE keyword is the conversion factor from the units of
  359.      (VX,VY) to the units of (X,Y) -- a time interval if (VX,VY) is a velocity
  360.      and (X,Y) is a position -- which determines the length of the
  361.      vector "darts" plotted at the (X,Y) points.  If omitted, SCALE is
  362.      chosen so that the longest ray arrows have a length comparable
  363.      to a "typical" zone size.
  364.      You can use the scalem keyword in pledit to make adjustments to the
  365.      SCALE factor computed by default.
  366.      The following keywords are legal (each has a separate help entry):
  367.    KEYWORDS: legend, hide
  368.          type, width, color, smooth
  369.              marks, marker, mspace, mphase
  370.          triangle, region
  371.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh, pledit,
  372.              limits, logxy, range, fma, hcp
  373.  */
  374.  
  375. extern plf;
  376. /* DOCUMENT plf, z, y, x
  377.          or plf, z, y, x, ireg
  378.      or plf, z
  379.      plots a filled mesh Y versus X.  Y, X, and IREG are as for plm.
  380.      The Z array must have the same shape as Y and X, or one smaller
  381.      in both dimensions.  If Z is of type char, it is used "as is",
  382.      otherwise it is linearly scaled to fill the current palette, as
  383.      with the bytscl function.
  384.      (See the bytscl function for explanation of top, cmin, cmax.)
  385.      The mesh is drawn with each zone in the color derived from the Z
  386.      function and the current palette; thus Z is interpreted as a
  387.      zone-centered array.
  388.      The Y, X, and IREG arguments may all be omitted to default to the
  389.      mesh set by the most recent plmesh call.
  390.      A solid edge can optionally be drawn around each zone by setting
  391.      the EDGES keyword non-zero.  ECOLOR and EWIDTH determine the edge
  392.      color and width.  The mesh is drawn zone by zone in order from
  393.      IREG(2+imax) to IREG(jmax*imax) (the latter is IREG(imax,jmax)),
  394.      so you can achieve 3D effects by arranging for this order to
  395.      coincide with back-to-front order.  If Z is nil, the mesh zones
  396.      are filled with the background color, which you can use to
  397.      produce 3D wire frames.
  398.      The following keywords are legal (each has a separate help entry):
  399.    KEYWORDS: legend, hide
  400.          region, top, cmin, cmax, edges, ecolor, ewidth
  401.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp, plmesh,
  402.              limits, logxy, range, fma, hcp, palette, bytscl, histeq_scale
  403.  */
  404.  
  405. extern plfp;
  406. /* DOCUMENT plfp, z, y, x, n
  407.      plots a list of filled polygons Y versus X, with colors Z.
  408.      The N array is a 1D list of lengths (number of corners) of the
  409.      polygons; the 1D colors array Z has the same length as N.  The
  410.      X and Y arrays have length sum(N).
  411.      The Z array must have the same shape as Y and X.  If Z is of
  412.      type char, it is used "as is", otherwise it is linearly scaled
  413.      to fill the current palette, as with the bytscl function.
  414.      (See the bytscl function for explanation of top, cmin, cmax.)
  415.      The following keywords are legal (each has a separate help entry):
  416.    KEYWORDS: legend, hide, top, cmin, cmax
  417.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj
  418.              limits, logxy, range, fma, hcp
  419.  */
  420.  
  421. extern pli;
  422. /* DOCUMENT pli, z
  423.          or pli, z, x1, y1
  424.          or pli, z, x0, y0, x1, y1
  425.      plots the image Z as a cell array -- an array of equal rectangular
  426.      cells colored according to the 2-D array Z.  The first dimension
  427.      of Z is plotted along x, the second dimension is along y.
  428.      If Z is of type char, it is used "as is", otherwise it is linearly
  429.      scaled to fill the current palette, as with the bytscl function.
  430.      (See the bytscl function for explanation of top, cmin, cmax.)
  431.      If X1 and Y1 are given, they represent the coordinates of the
  432.      upper right corner of the image.  If X0, and Y0 are given, they
  433.      represent the coordinates of the lower left corner, which is at
  434.      (0,0) by default.  If only the Z array is given, each cell will be
  435.      a 1x1 unit square, with the lower left corner of the image at (0,0).
  436.      The following keywords are legal (each has a separate help entry):
  437.    KEYWORDS: legend, hide, top, cmin, cmax
  438.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp,
  439.              limits, logxy, range, fma, hcp, palette, bytscl, histeq_scale
  440.  */
  441.  
  442. extern pldj;
  443. /* DOCUMENT pldj, x0, y0, x1, y1
  444.      plots disjoint lines from (X0,Y0) to (X1,Y1).  X0, Y0, X1, and Y1
  445.      may have any dimensionality, but all must have the same number of
  446.      elements.
  447.      The following keywords are legal (each has a separate help entry):
  448.    KEYWORDS: legend, hide
  449.          type, width, color
  450.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp
  451.              limits, logxy, range, fma, hcp
  452.  */
  453.  
  454. extern plt;
  455. /* DOCUMENT plt, text, x, y, tosys=0/1
  456.      plots TEXT (a string) at the point (X,Y).  The exact relationship
  457.      between the point (X,Y) and the TEXT is determined by the
  458.      justify keyword.  TEXT may contain newline ("\n") characters
  459.      to output multiple lines of text with a single call.  The
  460.      coordinates (X,Y) are NDC coordinates (outside of any coordinate
  461.      system) unless the tosys keyword is present and non-zero, in
  462.      which case the TEXT will be placed in the current coordinate
  463.      system.  However, the character height is NEVER affected by the
  464.      scale of the coordinate system to which the text belongs.
  465.      Note that the pledit command takes dx and/or dy keywords to
  466.      adjust the position of existing text elements.
  467.      The following keywords are legal (each has a separate help entry):
  468.    KEYWORDS: legend, hide
  469.          color, font, height, opaque, path, justify
  470.    SEE ALSO: plg, plm, plc, plv, plf, pli, plt, pldj, plfp, pledit
  471.              limits, range, fma, hcp, pltitle
  472.  */
  473.  
  474. func pltitle(title)
  475. /* DOCUMENT pltitle, title
  476.      Plot TITLE centered above the coordinate system for any of the
  477.      standard Gist styles.  You will need to customize this for other
  478.      plot styles.
  479.  */
  480. {
  481.   plt, title, 0.395, 0.870, font="helvetica", justify="CA", height=18;
  482. }
  483.  
  484. /*--------------------------------------------------------------------------*/
  485. /* Plot limits and log/linear scaling */
  486.  
  487. e= "e";         /* for use with limits and range functions */
  488.  
  489. extern limits;
  490. /* DOCUMENT limits
  491.          or limits, xmin, xmax, ymin, ymax,
  492.                 square=0/1, nice=0/1, restrict=0/1
  493.      or old_limits= limits()
  494.      or limits, old_limits
  495.  
  496.      In the first form, restores all four plot limits to extreme values.
  497.  
  498.      In the second form, sets the plot limits in the current coordinate
  499.      system to XMIN, XMAX, YMIN, YMAX, which may be nil or omitted to
  500.      leave the corresponding limit unchanged, a number to fix the
  501.      corresponding limit to a specified value, or the string "e" to
  502.      make the corresponding limit take on the extreme value of the
  503.      currently displayed data.
  504.  
  505.      If present, the square keyword determines whether limits marked
  506.      as extreme values will be adjusted to force the x and y scales
  507.      to be equal (square=1) or not (square=0, the default).
  508.      If present, the nice keyword determines whether limits will be
  509.      adjusted to nice values (nice=1) or not (nice=0, the default).
  510.      There is a subtlety in the meaning of "extreme value" when one
  511.      or both of the limits on the OPPOSITE axis have fixed values --
  512.      does the "extreme value" of the data include points which
  513.      will not be plotted because their other coordinate lies outside
  514.      the fixed limit on the opposite axis (restrict=0, the default),
  515.      or not (restrict=1)?
  516.  
  517.      If called as a function, limits returns an array of 5 doubles;
  518.      OLD_LIMITS(1:4) are the current xmin, xmax, ymin, and ymax,
  519.      and int(OLD_LIMITS(5)) is a set of flags indicating extreme
  520.      values and the square, nice, restrict, and log flags.
  521.  
  522.      In the fourth form, OLD_LIMITS is as returned by a previous
  523.      limits call, to restore the limits to a previous state.
  524.  
  525.      In an X window, the limits may also be adjusted interactively
  526.      with the mouse.  Drag left to zoom in and pan (click left to zoom
  527.      in on a point without moving it), drag middle to pan, and click
  528.      (and drag) right to zoom out (and pan).  If you click just above
  529.      or below the plot, these operations will be restricted to the
  530.      x-axis; if you click just to the left or right, the operations
  531.      are restricted to the y-axis.  A shift-left click, drag, and
  532.      release will expand the box you dragged over to fill the plot
  533.      (other popular software zooms with this paradigm).  If the
  534.      rubber band box is not visible with shift-left zooming, try
  535.      shift-middle or shift-right for alternate XOR masks.  Such
  536.      mouse-set limits are equivalent to a limits command specifying
  537.      all four limits EXCEPT that the unzoom command can revert to
  538.      the limits before a series of mouse zooms and pans.
  539.  
  540.      The limits you set using the limits or range functions carry over
  541.      to the next plot -- that is, an fma operation does NOT reset the
  542.      limits to extreme values.
  543.  
  544.    SEE ALSO: plsys, range, logxy, zoom_factor, unzoom, plg
  545.  */
  546.  
  547. func range(ymin, ymax) { limits,,, ymin, ymax; }
  548. /* DOCUMENT range, ymin, ymax
  549.      sets the y-axis plot limits in the current coordinate system to
  550.      YMIN, YMAX, which may be nil or omitted to leave the corresponding
  551.      limit unchanged, a number to fix the corresponding limit to a
  552.      specified value, or the string "e" to make the corresponding limit
  553.      take on the extreme value of the currently displayed data.
  554.      Use    limits, xmin, xmin
  555.      to accomplish the same function for the x-axis plot limits.
  556.    SEE ALSO: plsys, limits, logxy, plg
  557.  */
  558.  
  559. extern logxy;
  560. /* DOCUMENT logxy, xflag, yflag
  561.      sets the linear/log axis scaling flags for the current coordinate
  562.      system.  XFLAG and YFLAG may be nil or omitted to leave the
  563.      corresponding axis scaling unchanged, 0 to select linear scaling,
  564.      or 1 to select log scaling.
  565.    SEE ALSO: plsys, limits, range, plg, gridxy
  566.  */
  567.  
  568. extern gridxy;
  569. /* DOCUMENT gridxy, flag
  570.          or gridxy, xflag, yflag
  571.      Turns on or off grid lines according to FLAG.  In the first form, both
  572.      the x and y axes are affected.  In the second form, XFLAG and YFLAG
  573.      may differ to have different grid options for the two axes.  In either
  574.      case, a FLAG value of 0 means no grid lines (the default), a value of
  575.      1 means grid lines at all major ticks (the level of ticks which get
  576.      grid lines can be set in the style sheet), and a FLAG value of 2 means
  577.      that the coordinate origin only will get a grid line.  In styles with
  578.      multiple coordinate systems, only the current coordinate system is
  579.      affected.
  580.      The keywords can be used to affect the style of the grid lines.
  581.    KEYWORDS: color, type, width
  582.    SEE ALSO: window, plsys, limits, range, logxy
  583.  */
  584.  
  585. extern zoom_factor;
  586. /* DOCUMENT zoom_factor, factor
  587.      sets the zoom factor for mouse-click zoom in and zoom out operations.
  588.      The default FACTOR is 1.5; FACTOR should always be greater than 1.0.
  589.    SEE ALSO: limits, range, unzoom, plg
  590.  */
  591.  
  592. extern unzoom;
  593. /* DOCUMENT unzoom
  594.      restores limits to their values before zoom and pan operations
  595.      performed interactively using the mouse.
  596.      Use    old_limits=  limits()
  597.             ...
  598.         limits, old_limits
  599.      to save and restore plot limits generally.
  600.    SEE ALSO: limits, range, zoom_factor, plg
  601.  */
  602.  
  603. /*--------------------------------------------------------------------------*/
  604. /* Keywords for plotting functions */
  605.  
  606. local legend;
  607. /* DOCUMENT legend=   plotting keyword
  608.      sets the legend for a plot.  The default legend is a concatentation
  609.      of the strings used in the original plotting command (plg, plm, etc.),
  610.      except for the plt command, which has no default legend.
  611.      Legends are never plotted to the X window; use the plq command to
  612.      see them interactively.  Legends will appear in hardcopy output
  613.      unless they have been explicitly turned off.
  614.    PLOTTING COMMANDS: plg, plm, plc, plv, plf, pli, plt, pldj
  615.    SEE ALSO: hide
  616.  */
  617.  
  618. local hide;
  619. /* DOCUMENT hide=   plotting keyword
  620.      sets the visibility of a plotted element.  The default is hide=0,
  621.      which means that the element will be visible.  Use hide=1 to remove
  622.      the element from the plot (but not from the display list).
  623.    PLOTTING COMMANDS: plg, plm, plc, plv, plf, pli, plt, pldj
  624.    SEE ALSO: legend
  625.  */
  626.  
  627. local type;
  628. /* DOCUMENT type=   plotting keyword
  629.      selects line type.  Valid values are the strings "solid", "dash",
  630.      "dot", "dashdot", "dashdotdot", and "none".  The "none" value
  631.      causes the line to be plotted as a polymarker.
  632.      The type value may also be a number; 0 is "none", 1 is "solid",
  633.      2 is "dash", 3 is "dot", 4 is "dashdot", and 5 is "dashdotdot".
  634.    PLOTTING COMMANDS: plg, plm, plc, pldj
  635.    SEE ALSO: width, color, marks, marker, rays, closed, smooth
  636.  */
  637.  
  638. local width;
  639. /* DOCUMENT width=   plotting keyword
  640.      selects line width.  Valid values are positive floating point numbers
  641.      giving the line thickness relative to the default line width of one
  642.      half point, width= 1.0.
  643.    PLOTTING COMMANDS: plg, plm, plc, pldj, plv (only if hollow=1)
  644.    SEE ALSO: type, color, marks, marker, rays, closed, smooth
  645.  */
  646.  
  647. local color;
  648. /* DOCUMENT color=   plotting keyword
  649.      selects line or text color.  Valid values are the strings "bg", "fg",
  650.      "black", "white", "red", "green", "blue", "cyan", "magenta", "yellow",
  651.      or a 0-origin index into the current palette.  The default is "fg".
  652.      Negative numbers may be used instead of the strings: -1 is bg
  653.      (background), -2 is fg (foreground), -3 is black, -4 is white,
  654.      -5 is red, -6 is green, -7 is blue, -8 is cyan, -9 is magenta, and
  655.      -10 is yellow.
  656.    PLOTTING COMMANDS: plg, plm, plc, pldj, plt
  657.    SEE ALSO: type, width, marks, marker, mcolor, rays, closed, smooth
  658.  */
  659.  
  660. local marks;
  661. /* DOCUMENT marks=   plotting keyword
  662.      selects unadorned lines (marks=0), or lines with occasional markers
  663.      (marks=1).  Ignored if type is "none" (indicating polymarkers instead
  664.      of occasional markers).  The spacing and phase of the occasional
  665.      markers can be altered using the mspace and mphase keywords; the
  666.      character used to make the mark can be altered using the marker
  667.      keyword.
  668.    PLOTTING COMMANDS: plg, plc
  669.    SEE ALSO: type, width, color, marker, rays, mspace, mphase, msize, mcolor
  670.  */
  671.  
  672. local marker;
  673. /* DOCUMENT marker=   plotting keyword
  674.      selects the character used for occasional markers along a polyline,
  675.      or for the polymarker if type is "none".  The special values
  676.      '\1', '\2', '\3', '\4', and '\5' stand for point, plus, asterisk,
  677.      circle, and cross, which are prettier than text characters on output
  678.      to some devices.  The default marker is the next available capital
  679.      letter, 'A', 'B', ..., 'Z'.
  680.    PLOTTING COMMANDS: plg, plc
  681.    SEE ALSO: type, width, color, marks, rays, mspace, mphase, msize, mcolor
  682.  */
  683.  
  684. local mspace, mphase, msize, mcolor;
  685. /* DOCUMENT mspace=   plotting keyword
  686.          or mphase=   plotting keyword
  687.          or msize=    plotting keyword
  688.          or mcolor=   plotting keyword
  689.      selects the spacing, phase, and size of occasional markers placed
  690.      along polylines.  The msize also selects polymarker size if type
  691.      is "none".  The spacing and phase are in NDC units (0.0013 NDC
  692.      equals 1.0 point); the default mspace is 0.16, and the default
  693.      mphase is 0.14, but mphase is automatically incremented for
  694.      successive curves on a single plot.  The msize is in relative
  695.      units, with the default msize of 1.0 representing 10 points.
  696.      The mcolor keyword is the same as the color keyword, but controls
  697.      the marker color instead of the line color.  Setting the color
  698.      automatically sets the mcolor to the same value, so you only
  699.      need to use mcolor if you want the markers for a curve to be a
  700.      different color than the curve itself.
  701.    PLOTTING COMMANDS: plg, plc
  702.    SEE ALSO: type, width, color, marks, marker, rays
  703.  */
  704.  
  705. local rays;
  706. /* DOCUMENT rays=   plotting keyword
  707.      selects unadorned lines (rays=0), or lines with occasional ray
  708.      arrows (rays=1).  Ignored if type is "none".  The spacing and phase
  709.      of the occasional arrows can be altered using the rspace and rphase
  710.      keywords; the shape of the arrowhead can be modified using the
  711.      arroww and arrowl keywords.
  712.    PLOTTING COMMANDS: plg, plc
  713.    SEE ALSO: type, width, color, marker, marks, rspace, rphase
  714.              arroww, arrowl
  715.  */
  716.  
  717. local rspace, rphase, arroww, arrowl;
  718. /* DOCUMENT rspace=   plotting keyword
  719.          or rphase=   plotting keyword
  720.          or arroww=   plotting keyword
  721.          or arrowl=   plotting keyword
  722.      selects the spacing, phase, and size of occasional ray arrows
  723.      placed along polylines.  The spacing and phase are in NDC units
  724.      (0.0013 NDC equals 1.0 point); the default rspace is 0.13, and
  725.      the default rphase is 0.11375, but rphase is automatically
  726.      incremented for successive curves on a single plot.
  727.      The arrowhead width, arroww, and arrowhead length, arrowl are
  728.      in relative units, defaulting to 1.0, which translates to an
  729.      arrowhead 10 points long and 4 points in half-width.
  730.    PLOTTING COMMANDS: plg
  731.    SEE ALSO: type, width, color, marks, marker, rays
  732.  */
  733.  
  734. local closed, smooth;
  735. /* DOCUMENT closed=   plotting keyword
  736.          or smooth=   plotting keyword
  737.      selects closed curves (closed=1) or default open curves (closed=0),
  738.      or Bezier smoothing (smooth>0) or default piecewise linear curves
  739.      (smooth=0).  The value of smooth can be 1, 2, 3, or 4 to get
  740.      successively more smoothing.  Only the Bezier control points are
  741.      plotted to an X window; the actual Bezier curves will show up in
  742.      PostScript hardcopy files.  Closed curves join correctly, which
  743.      becomes more noticeable for wide lines; non-solid closed curves
  744.      may look bad because the dashing pattern may be incommensurate
  745.      with the length of the curve.
  746.    PLOTTING COMMANDS: plg, plc (smooth only)
  747.    SEE ALSO: type, width, color, marks, marker, rays
  748.  */
  749.  
  750. local font, height, opaque, path, justify;
  751. /* DOCUMENT font=     plotting keyword
  752.          or height=   plotting keyword
  753.          or opaque=   plotting keyword
  754.          or path=     plotting keyword
  755.          or justify=  plotting keyword
  756.      selects text properties.  The font can be any of the strings
  757.      "courier", "times", "helvetica" (the default), "symbol", or
  758.      "schoolbook".  Append "B" for boldface and "I" for italic, so
  759.      "courierB" is boldface Courier, "timesI" is Times italic, and
  760.      "helveticaBI" is bold italic (oblique) Helvetica.  Your X server
  761.      should have the Adobe fonts (available free from the MIT X
  762.      distribution tapes) for all these fonts, preferably at both 75
  763.      and 100 dpi.  Occasionally, a PostScript printer will not be
  764.      equipped for some fonts; often New Century Schoolbook is missing.
  765.      The font keyword may also be an integer: 0 is Courier, 4 is Times,
  766.      8 is Helvetica, 12 is Symbol, 16 is New Century Schoolbook, and
  767.      you add 1 to get boldface and/or 2 to get italic (or oblique).
  768.  
  769.      The height is the font size in points; 14.0 is the default.
  770.      X windows only has 8, 10, 12, 14, 18, and 24 point fonts, so
  771.      don't stray from these sizes if you want what you see on the
  772.      screen to be a reasonably close match to what will be printed.
  773.  
  774.      By default, opaque=0 and text is transparent.  Set opaque=1 to
  775.      white-out a box before drawing the text.  The default path
  776.      (path=0) is left-to-right text; set path=1 for top-to-bottom text.
  777.  
  778.      The default text justification, justify="NN" is normal is both
  779.      the horizontal and vertical directions.  Other possibilities
  780.      are "L", "C", or "R" for the first character, meaning left,
  781.      center, and right horizontal justification, and "T", "C", "H",
  782.      "A", or "B", meaning top, capline, half, baseline, and bottom
  783.      vertical justification.  The normal justification "NN" is equivalent
  784.      to "LA" if path=0, and to "CT" if path=1.  Common values are
  785.      "LA", "CA", and "RA" for garden variety left, center, and right
  786.      justified text, with the y coordinate at the baseline of the
  787.      last line in the string presented to plt.  The characters labeling
  788.      the right axis of a plot are "RH", so that the y value of the
  789.      text will match the y value of the corresponding tick.  Similarly,
  790.      the characters labeling the bottom axis of a plot are "CT".
  791.      The justification may also be a number, horizontal+vertical,
  792.      where horizontal is 0 for "N", 1 for "L", 2 for "C", or 3 for "R",
  793.      and vertical is 0 for "N", 4 for "T", 8 for "C", 12 for "H",
  794.      16 for "A", or 20 for "B".
  795.  
  796.    PLOTTING COMMANDS: plt
  797.    SEE ALSO: color
  798.  */
  799.  
  800. local region;
  801. /* DOCUMENT region=   plotting keyword
  802.      selects the part of mesh to consider.  The region should match one
  803.      of the numbers in the IREG array.  Putting region=0 (the default)
  804.      means to plot the entire mesh, that is, everything EXCEPT region
  805.      zero (non-existent zones).  Any other number means to plot only
  806.      the specified region number; region=3 would plot region 3 only.
  807.    PLOTTING COMMANDS: plm, plc, plv, plf
  808.  */
  809.  
  810. local triangle;
  811. /* DOCUMENT triangle=   plotting keyword
  812.      sets the triangulation array for a contour plot.  The triangulation
  813.      array must be the same shape as the IREG (region number) array, and
  814.      the correspondence between mesh zones and indices is the same as
  815.      for IREG.  The triangulation array is used to resolve the ambiguity
  816.      in saddle zones, in which the function Z being contoured has two
  817.      diagonally opposite corners high, and the other two corners low.
  818.      The triangulation array element for a zone is 0 if the algorithm is
  819.      to choose a triangulation, based on the curvature of the first
  820.      contour to enter the zone.  If zone (i,j) is to be triangulated
  821.      from point (i-1,j-1) to point (i,j), then TRIANGLE(i,j)=1,
  822.      while if it is to be triangulated from (i-1,j) to (i,j-1), then
  823.      TRIANGLE(i,j)=-1.  Contours will never cross this "triangulation
  824.      line".
  825.      You should rarely need to fiddle with the traingulation array;
  826.      it is a hedge for dealing with pathological cases.
  827.    PLOTTING COMMANDS: plc
  828.  */
  829.  
  830. local hollow, aspect;
  831. /* DOCUMENT hollow=   plotting keyword
  832.          or aspect=   plotting keyword
  833.      set the appearance of the "darts" of a vector field plot.  The
  834.      default darts, hollow=0, are filled; use hollow=1 to get just the
  835.      dart outlines.  The default is aspect=0.125; aspect is the ratio
  836.      of the half-width to the length of the darts.  Use the color
  837.      keyword to control the color of the darts.
  838.    PLOTTING COMMANDS: plv
  839.    SEE ALSO: color
  840.  */
  841.  
  842. local edges, ecolor, ewidth;
  843. /* DOCUMENT edges=   plotting keyword
  844.          or ecolor=   plotting keyword
  845.          or ewidth=   plotting keyword
  846.      set the appearance of the zone edges in a filled mesh plot (plf).
  847.      By default, edges=0, and the zone edges are not plotted.  If
  848.      edges=1, a solid line is drawn around each zone after it is
  849.      filled; the edge color and width are given by ecolor and ewidth,
  850.      which are "fg" and 1.0 by default.
  851.    PLOTTING COMMANDS: plf
  852.    SEE ALSO: color, width
  853.  */
  854.  
  855. /*--------------------------------------------------------------------------*/
  856. /* Inquiry and editing functions */
  857.  
  858. extern plq;
  859. /* DOCUMENT plq
  860.          or plq, n_element
  861.      or plq, n_element, n_contour
  862.      or legend_list= plq()
  863.      or properties= plq(n_element, n_contour)
  864.      Called as a subroutine, prints the list of legends for the current
  865.      coordinate system (with an "(H)" to mark hidden elements), or prints
  866.      a list of current properties of element N_ELEMENT (such as line type,
  867.      width, font, etc.), or of contour number N_CONTOUR of element number
  868.      N_ELEMENT (which must be contours generated using the plc command).
  869.      Called as a function, returns either the list of legend strings, or a
  870.      list of pointers to the values of the various element properties.
  871.      Elements and contours are both numbered starting with one; hidden
  872.      elements or contours are included in this numbering.
  873.  
  874.      The PROPERTIES list returned by plq is a list of pointers to the
  875.      relevent properties for the specified graphical element.  Each
  876.      possible property has a particular index in the returned PROPERTIES
  877.      list as follows:
  878.      *PROPERTIES(1)   int([element type (0 for none, 1 for plg, 2 for pldj,
  879.                                          3 for plt, 4 for plm, 5 for plf,
  880.                      6 for plv, 7 for plc, 8 for pli,
  881.                      9 for plfp),
  882.                            hide flag])
  883.      *PROPERTIES(2)   string(legend)
  884.      *PROPERTIES(3)   int array, depends on type (names match keywords):
  885.        1 plg:  [color, type, marks, mcolor, marker, rays, closed, smooth]
  886.        2 pldj: [color, type]
  887.        3 plt:  [color, font, path, justify, opaque]
  888.        4 plm:  [color, type, region, boundary, inhibit]
  889.        5 plf:  [region, edges, ecolor]
  890.        6 plv:  [region, color, hollow]
  891.        7 plc:  [region, color, type, marks, mcolor, marker, smooth]
  892.        8 pli:  nil
  893.      *PROPERTIES(4)   double array, depends on type (names match keywords):
  894.        1 plg:  [width, msize, mspace, mphase, rspace, rphase, arrowl, arroww]
  895.        2 pldj: [width]
  896.        3 plt:  [height, x, y]
  897.        4 plm:  [width]
  898.        5 plf:  [ewidth]
  899.        6 plv:  [width, aspect, scale]
  900.        7 plc:  [width, msize, mspace, mphase]
  901.        8 pli:  [x0, x1, y0, y1]
  902.      *PROPERTIES(5)   long array, depends on type (names match arguments):
  903.        1 plg:  [npoints, &x, &y]
  904.        2 pldj: [npoints, &x0, &y0, &x1, &y1]
  905.        3 plt:  [nchars, &text]
  906.        4 plm:  [imax, jmax, &x, &y, &ireg]
  907.        5 plf:  [imax, jmax, &x, &y, &ireg, &colors]
  908.        6 plv:  [imax, jmax, &x, &y, &ireg, &vx, &vy]
  909.        7 plc:  [imax, jmax, &x, &y, &ireg, &z, &triangle, nlevs, &levs]
  910.        8 pli:  [imax, jmax, &colors]
  911.        9 plfp: [n, &x, &y, &colors, &pn]
  912.      You can use the reshape function to peek at the data at the addresses
  913.      returned in PROPERTIES(5) as longs.  The appropriate data types are:
  914.      char for text, int for ireg, short for triangle, char for colors, and
  915.      double for everything else.  In a plf, colors is (imax-1)-by-(jmax-1).
  916.      Although PROPERTIES(5) returns pointers to the data plotted, attempting
  917.      to poke new values into this data will not produce immediate changes
  918.      to your plot, since the graphics package does not realize that anything
  919.      has changed.  Use pledit to make changes to plotted elements.
  920.  
  921.      The plq function always operates on the current coordinate system
  922.      in the current graphics window; use window and plsys to change these.
  923.    SEE ALSO: window, plsys, pledit, pldefault, plg
  924.  */
  925.  
  926. extern pledit;
  927. /* DOCUMENT pledit, key1=value1, key2=value2, ...
  928.          or pledit, n_element, key1=value1, key2=value2, ...
  929.          or pledit, n_element, n_contour, key1=value1, key2=value2, ...
  930.      changes some property of element number N_ELEMENT (and contour
  931.      number N_CONTOUR of that element).  If N_ELEMENT and N_CONTOUR are
  932.      omitted, the default is the most recently added element, or the
  933.      element specified in the most recent plq query command.
  934.  
  935.      The keywords can be any of the keywords that apply to the current
  936.      element.  These are:
  937.        plg:  color, type, width,
  938.              marks, mcolor, marker, msize, mspace, mphase,
  939.          rays, rspace, rphase, arrowl, arroww,
  940.          closed, smooth
  941.        pldj: color, type, width
  942.        plt:  color, font, height, path, justify, opaque
  943.        plm:  region, boundary, inhibit, color, type, width
  944.        plf:  region
  945.        plv:  region, color, hollow, width, aspect, scale
  946.        plc:  region, color, type, width,
  947.              marks, mcolor, marker, msize, mspace, mphase
  948.          smooth, levs
  949.      (For contours, if you aren't talking about a particular N_CONTOUR,
  950.       any changes will affect ALL the contours.)
  951.  
  952.      A plv (vector field) element can also take the scalem
  953.      keyword to multiply all vector lengths by a specified factor.
  954.  
  955.      A plt (text) element can also take the dx and/or dy
  956.      keywords to adjust the text position by (dx,dy).
  957.  
  958.    SEE ALSO: window, plsys, plq, pldefault, plg
  959.  */
  960.  
  961. extern pldefault;
  962. /* DOCUMENT pldefault, key1=value1, key2=value2, ...
  963.      sets default values for the various properties of graphical elements.
  964.  
  965.      The keywords can be most of the keywords that can be passed to the
  966.      plotting commands:
  967.        plg:  color, type, width,
  968.              marks, mcolor, msize, mspace, mphase,
  969.          rays, rspace, rphase, arrowl, arroww
  970.        pldj: color, type, width
  971.        plt:  color, font, height, path, justify, opaque
  972.        plm:  color, type, width
  973.        plv:  color, hollow, width, aspect
  974.        plc:  color, type, width,
  975.              marks, mcolor, marker, msize, mspace, mphase
  976.        plf:  edges, ecolor, ewidth
  977.  
  978.      The initial default values are:
  979.        color="fg", type="solid", width=1.0 (1/2 point),
  980.        marks=1, mcolor="fg", msize=1.0 (10 points),
  981.           mspace=0.16, mphase=0.14,
  982.        rays=0, arrowl=1.0 (10 points), arroww=1.0 (4 points),
  983.           rspace=0.13, rphase=0.11375,
  984.        font="helvetica", height=12.0, path=0, justify="NN", opaque=0,
  985.        hollow= 0, aspect=0.125,
  986.        edges=0, ecolor="fg", ewidth=1.0 (1/2 point)
  987.  
  988.      Additional default keywords are:
  989.        dpi, style, legends  (see window command)
  990.        palette              (to set default filename as in palette command)
  991.        maxcolors            (default 200)
  992.  
  993.    SEE ALSO: window, plsys, plq, pledit, plg
  994.  */
  995.  
  996. /*--------------------------------------------------------------------------*/
  997. /* Miscellany */
  998.  
  999. extern bytscl;
  1000. /* DOCUMENT bytscl(z)
  1001.          or bytscl(z, top=max_byte, cmin=lower_cutoff, cmax=upper_cutoff)
  1002.      returns a char array of the same shape as Z, with values linearly
  1003.      scaled to the range 0 to one less than the current palette size.
  1004.      If MAX_BYTE is specified, the scaled values will run from 0 to
  1005.      MAX_BYTE instead.
  1006.      If LOWER_CUTOFF and/or UPPER_CUTOFF are specified, Z values outside
  1007.      this range are mapped to the cutoff value; otherwise the linear
  1008.      scaling maps the extreme values of Z to 0 and MAX_BYTE.
  1009.    SEE ALSO: plf, pli, histeq_scale
  1010.  */
  1011.  
  1012. extern mesh_loc;
  1013. /* DOCUMENT mesh_loc(y0, x0)
  1014.          or mesh_loc(y0, x0, y, x)
  1015.          or mesh_loc(y0, x0, y, x, ireg)
  1016.      returns the zone index (=i+imax*(j-1)) of the zone of the mesh
  1017.      (X,Y) (with optional region number array IREG) containing the
  1018.      point (X0,Y0).  If (X0,Y0) lies outside the mesh, returns 0.
  1019.      Thus, eg- ireg(mesh_loc(x0, y0, y, x, ireg)) is the region number of
  1020.      the region containing (x0,y0).  If no mesh specified, uses default.
  1021.      X0 and Y0 may be arrays as long as they are conformable.
  1022.    SEE ALSO: plmesh, moush, mouse
  1023.  */
  1024.  
  1025. extern mouse;
  1026. /* DOCUMENT result= mouse(system, style, prompt)
  1027.      displays a PROMPT, then waits for a mouse button to be pressed,
  1028.      then released.  Returns array of eleven doubles:
  1029.        result= [x_pressed, y_pressed, x_released, y_released,
  1030.                 xndc_pressed, yndc_pressed, xndc_released, yndc_released,
  1031.             system, button, modifiers]
  1032.  
  1033.      If SYSTEM>=0, the first four coordinate values will be relative to
  1034.      that coordinate system.
  1035.      For SYSTEM<0, the first four coordinate values will be relative to
  1036.      the coordinate system under the mouse when the button was pressed.
  1037.      The second four coordinates are always normalized device coordinates,
  1038.      which start at (0,0) in the lower left corner of the 8.5x11 sheet of
  1039.      paper the picture will be printed on, with 0.0013 NDC unit being
  1040.      1/72.27 inch (1.0 point).  Look in the style sheet for the location
  1041.      of the viewport in NDC coordinates (see the style keyword).
  1042.  
  1043.      If STYLE is 0, there will be no visual cues that the mouse
  1044.      command has been called; this is intended for a simple click.
  1045.      If STYLE is 1, a rubber band box will be drawn; if STYLE is 2,
  1046.      a rubber band line will be drawn.  These disappear when the
  1047.      button is released.
  1048.  
  1049.      Clicking a second button before releasing the first cancels the
  1050.      mouse function, which will then return nil.
  1051.      Ordinary text input also cancels the mouse function, which again
  1052.      returns nil.
  1053.  
  1054.      The left button reverses forground for background (by XOR) in
  1055.      order to draw the rubber band (if any).  The middle and right
  1056.      buttons use other masks, in case the rubber band is not visible
  1057.      with the left button.
  1058.  
  1059.      long(result(9)) is the coordinate system in which the first four
  1060.      coordinates are to be interpreted.
  1061.      long(result(10)) is the button which was pressed, 1 for left, 2
  1062.      for middle, and 3 for right (4 and 5 are also possible).
  1063.      long(result(11)) is a mask representing the modifier keys which
  1064.      were pressed during the operation: 1 for shift, 2 for shift lock,
  1065.      4 for control, 8 for mod1 (alt or meta), 16 for mod2, 32 for mod3,
  1066.      64 for mod4, and 128 for mod5.
  1067.  
  1068.    SEE ALSO: moush
  1069.  */
  1070.  
  1071. func moush(y, x, ireg)
  1072. /* DOCUMENT moush()
  1073.          or moush(y, x, ireg)
  1074.      returns the 1-origin zone index for the point clicked in
  1075.      for the default mesh, or for the mesh (X,Y) (region array IREG).
  1076.  */
  1077. {
  1078.   xy= mouse(-1, 0, "<Click mouse in mesh>");
  1079.   if (is_void(xy)) return [];
  1080.   else return mesh_loc(xy(2), xy(1), y, x, ireg);
  1081. }
  1082.  
  1083. extern pause;
  1084. /* DOCUMENT pause, milliseconds
  1085.      pause for the specified number of milliseconds of wall clock
  1086.      time, or until input arrives from the keyboard.
  1087.      This is intended for use in creating animated sequences.
  1088.  */
  1089.  
  1090. /*--------------------------------------------------------------------------*/
  1091.  
  1092. func histeq_scale(z, top=, cmin=, cmax=)
  1093. /* DOCUMENT histeq_scale(z, top=top_value, cmin=cmin, cmax=cmax)
  1094.      returns a byte-scaled version of the array Z having the property
  1095.      that each byte occurs with equal frequency (Z is histogram
  1096.      equalized).  The result bytes range from 0 to TOP_VALUE, which
  1097.      defaults to one less than the size of the current palette (or
  1098.      255 if no pli, plf, or palette command has yet been issued).
  1099.  
  1100.      If non-nil CMIN and/or CMAX is supplied, values of Z beyond these
  1101.      cutoffs are not included in the frequency counts.
  1102.  
  1103.    SEE ALSO: bytscl, plf, pli
  1104.  */
  1105. {
  1106.   if (is_void(top)) top= bytscl([0.,1.])(2);  /* palette size - 1 */
  1107.   top= long(top);
  1108.   if (top<0 | top>255) error, "top value out of range 0-255";
  1109.   y= z(*);
  1110.   if (!is_void(cmin)) y= y(where(y>=cmin));
  1111.   if (!is_void(cmax)) y= y(where(y<=cmax));
  1112.   y= y(sort(y));
  1113.   x= span(0.,1., numberof(y));
  1114.   xp= span(0.,1., top+2);
  1115.   bins= interp(y, x, xp);
  1116.   list= where(bins(dif)<=0.0);
  1117.   if (numberof(list)) {
  1118.     /* some value (or values) of z are repeated many times --
  1119.        try to handle this by adding a small slope to the sorted y */
  1120.     dy= y(0)-y(1);
  1121.     if (!dy) dy= 1.0;
  1122.     for (eps=1.e-10 ; eps<1000.1 ; eps*=10.) {
  1123.       bins= interp(y+eps*dy*x, x, xp);
  1124.       list= where(bins(dif)<=0.0);
  1125.       if (!numberof(list)) break;
  1126.     }
  1127.     if (eps>1000.) error, "impossible error??";
  1128.   }
  1129.   return char(max(min(digitize(z,bins)-2,top),0));
  1130. }
  1131.  
  1132. /*--------------------------------------------------------------------------*/
  1133.  
  1134. extern _pl_init;
  1135. /* xxDOCUMENT _pl_init
  1136.      initializes the Gist graphics package -- DON'T EVER CALL THIS.
  1137.  */
  1138. _pl_init, GISTPATH; /* ...except right here (see paths.i) */
  1139.